<!doctype html>
<html lang="zh-CN">
<head>
  <base href="https://www.nodeapp.cn/querystring.html" />
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width">
  <title>查询字符串 | Node.js 中文文档 | Node.js 中文网</title>
  <meta name="description" content="Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行环境。Node.js 使用了一个事件驱动、非阻塞式 I/O 的模型，使其轻量又高效。Node.js 的包管理器 npm，是全球最大的开源库生态系统。">
  <link rel="stylesheet" href="assets/style.css">
  <link rel="stylesheet" href="assets/sh.css">
  <link rel="canonical" href="https://www.nodeapp.cn/querystring.html">
  <link rel="apple-touch-icon" href="apple-touch-icon.png">
  <link rel="icon" sizes="32x32" type="image/png" href="favicon.png">
  
  <script>
var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?acdf78480f7f8f2b23b812565a5868e0";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();
</script>

</head>
<body class="alt apidoc" id="api-section-querystring">
  <div id="content" class="clearfix">
    <div id="column1" data-id="querystring" class="interior">
      <header>
        <h1>Node.js v8.x 中文文档</h1>
        <hr>
      </header>

      <div id="toc">
        <h2>目录</h2>
        <ul>
<li><span class="stability_2"><a href="#querystring_query_string">querystring - 查询字符串</a></span><ul>
<li><span class="stability_undefined"><a href="#querystring_querystring_escape_str">querystring.escape(str)</a></span></li>
<li><span class="stability_undefined"><a href="#querystring_querystring_parse_str_sep_eq_options">querystring.parse(str[, sep[, eq[, options]]])</a></span></li>
<li><span class="stability_undefined"><a href="#querystring_querystring_stringify_obj_sep_eq_options">querystring.stringify(obj[, sep[, eq[, options]]])</a></span></li>
<li><span class="stability_undefined"><a href="#querystring_querystring_unescape_str">querystring.unescape(str)</a></span></li>
</ul>
</li>
</ul>

      </div>
<div id="apicontent">
        <h1>querystring - 查询字符串<span><a class="mark" href="#querystring_query_string" id="querystring_query_string">#</a></span></h1>
<!--introduced_in=v0.10.0-->
<div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">稳定性: 2</a> - 稳定的</div><!--name=querystring-->
<p><code>querystring</code> 模块提供了一些实用函数，用于解析与格式化 URL 查询字符串。
使用以下方法引入：</p>
<pre><code class="lang-js">const querystring = require(&apos;querystring&apos;);
</code></pre>
<h2>querystring.escape(str)<span><a class="mark" href="#querystring_querystring_escape_str" id="querystring_querystring_escape_str">#</a></span></h2>
<div class="api_metadata">
<span>新增于: v0.1.25</span>
</div><ul>
<li><code>str</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string&gt;</a></li>
</ul>
<p>对给定的 <code>str</code> 进行 URL 编码。</p>
<p>该方法是提供给 <code>querystring.stringify()</code> 使用的，通常不直接使用。
它之所以对外开放，是为了在需要时可以通过给 <code>querystring.escape</code> 赋值一个函数来重写编码的实现。</p>
<h2>querystring.parse(str[, sep[, eq[, options]]])<span><a class="mark" href="#querystring_querystring_parse_str_sep_eq_options" id="querystring_querystring_parse_str_sep_eq_options">#</a></span></h2>
<div class="api_metadata">
<details class="changelog"><summary>版本历史</summary>
<table>
<tbody><tr><th>版本</th><th>变更</th></tr>
<tr><td>v8.0.0</td>
<td><p>Multiple empty entries are now parsed correctly (e.g. <code>&amp;=&amp;=</code>).</p>
</td></tr>
<tr><td>v6.0.0</td>
<td><p>The returned object no longer inherits from <code>Object.prototype</code>.</p>
</td></tr>
<tr><td>v6.0.0, v4.2.4</td>
<td><p>The <code>eq</code> parameter may now have a length of more than <code>1</code>.</p>
</td></tr>
<tr><td>v0.1.25</td>
<td><p><span>新增于: v0.1.25</span></p>
</td></tr>
</tbody></table>
</details>
</div><ul>
<li><code>str</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string&gt;</a> 要解析的 URL 查询字符串。</li>
<li><code>sep</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string&gt;</a> 用于界定查询字符串中的键值对的子字符串。默认为 <code>&apos;&amp;&apos;</code>。</li>
<li><code>eq</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string&gt;</a> 用于界定查询字符串中的键与值的子字符串。默认为 <code>&apos;=&apos;</code>。</li>
<li><code>options</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type">&lt;Object&gt;</a><ul>
<li><code>decodeURIComponent</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type">&lt;Function&gt;</a> 解码查询字符串的字符时使用的函数。默认为 <code>querystring.unescape()</code>。</li>
<li><code>maxKeys</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type">&lt;number&gt;</a> 指定要解析的键的最大数量。默认为 <code>1000</code>。指定为 <code>0</code> 则不限制。</li>
</ul>
</li>
</ul>
<p>该方法会把一个 URL 查询字符串 <code>str</code> 解析成一个键值对的集合。</p>
<p>例子，查询字符串 <code>&apos;foo=bar&amp;abc=xyz&amp;abc=123&apos;</code> 被解析成：</p>
<!-- eslint-skip -->
<pre><code class="lang-js">{
  foo: &apos;bar&apos;,
  abc: [&apos;xyz&apos;, &apos;123&apos;]
}
</code></pre>
<p>该方法返回的对象不继承自 JavaScript 的 <code>Object</code> 类。
这意味着 <code>Object</code> 类的方法如 <code>obj.toString()</code>、<code>obj.hasOwnProperty()</code> 等没有被定义且无法使用。</p>
<p>默认情况下，查询字符串中的字符会被视为使用 UTF-8 编码。
如果使用的是其他字符编码，则需要指定 <code>decodeURIComponent</code> 选项，例如：</p>
<pre><code class="lang-js">// 假设存在 gbkDecodeURIComponent 函数。
querystring.parse(&apos;w=%D6%D0%CE%C4&amp;foo=bar&apos;, null, null,
                  { decodeURIComponent: gbkDecodeURIComponent });
</code></pre>
<h2>querystring.stringify(obj[, sep[, eq[, options]]])<span><a class="mark" href="#querystring_querystring_stringify_obj_sep_eq_options" id="querystring_querystring_stringify_obj_sep_eq_options">#</a></span></h2>
<div class="api_metadata">
<span>新增于: v0.1.25</span>
</div><ul>
<li><code>obj</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type">&lt;Object&gt;</a> 要序列化成 URL 查询字符串的对象。</li>
<li><code>sep</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string&gt;</a> 用于界定查询字符串中的键值对的子字符串。默认为 <code>&apos;&amp;&apos;</code>。</li>
<li><code>eq</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string&gt;</a> 用于界定查询字符串中的键与值的子字符串。默认为 <code>&apos;=&apos;</code>。</li>
<li><code>options</code><ul>
<li><code>encodeURIComponent</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type">&lt;Function&gt;</a> 把对象中的字符转换成查询字符串时使用的函数。默认为 <code>querystring.escape()</code>。</li>
</ul>
</li>
</ul>
<p>该方法通过遍历给定的 <code>obj</code> 对象的自身属性，生成 URL 查询字符串。</p>
<p>如果 <code>obj</code> 对象中的属性的类型为 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string&gt;</a> | 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type">&lt;number&gt;</a> | 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type">&lt;boolean&gt;</a> | 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string[]&gt;</a> | 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type">&lt;number[]&gt;</a> | 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type">&lt;boolean[]&gt;</a>，则属性的值会被序列化。
其他类型的属性的值会被强制转换为空字符串。</p>
<p>例子：</p>
<pre><code class="lang-js">querystring.stringify({ foo: &apos;bar&apos;, baz: [&apos;qux&apos;, &apos;quux&apos;], corge: &apos;&apos; });
// 返回 &apos;foo=bar&amp;baz=qux&amp;baz=quux&amp;corge=&apos;

querystring.stringify({ foo: &apos;bar&apos;, baz: &apos;qux&apos; }, &apos;;&apos;, &apos;:&apos;);
// 返回 &apos;foo:bar;baz:qux&apos;
</code></pre>
<p>默认情况下，使用 UTF-8 进行编码。
如果需要使用其他编码，则需要指定 <code>encodeURIComponent</code> 选项，例如：</p>
<pre><code class="lang-js">// 假设存在 gbkEncodeURIComponent 函数。
querystring.stringify({ w: &apos;中文&apos;, foo: &apos;bar&apos; }, null, null,
                      { encodeURIComponent: gbkEncodeURIComponent });
</code></pre>
<h2>querystring.unescape(str)<span><a class="mark" href="#querystring_querystring_unescape_str" id="querystring_querystring_unescape_str">#</a></span></h2>
<div class="api_metadata">
<span>新增于: v0.1.25</span>
</div><ul>
<li><code>str</code> 
            <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string&gt;</a></li>
</ul>
<p>对给定的 <code>str</code> 进行解码。</p>
<p>该方法是提供给 <code>querystring.parse()</code> 使用的，通常不直接使用。
它之所以对外开放，是为了在需要时可以通过给 <code>querystring.unescape</code> 赋值一个函数来重写解码的实现。</p>
<p>默认使用 JavaScript 内置的 <code>decodeURIComponent()</code> 方法来解码。</p>

      </div>
    </div>

    <div id="column2" class="interior">
      <div id="intro" class="interior">
        <a href="/" title="Go back to the home page">
          Node.js 中文文档 | Node.js 中文网
        </a>
      </div>
      
        <!-- [start-include:_toc.md] -->
<ul>
<li><a href="documentation.html">关于本文档</a></li>
<li><a href="synopsis.html">用法与例子</a></li>
</ul>
<div class="line"></div>

<ul>
<li><a href="assert.html">断言测试</a></li>
<li><a href="async_hooks.html">异步钩子（Async Hooks）</a></li>
<li><a href="buffer.html">缓存（Buffer）</a></li>
<li><a href="addons.html">C++ 插件</a></li>
<li><a href="n-api.html">C/C++ 插件 - N-API</a></li>
<li><a href="child_process.html">子进程</a></li>
<li><a href="cluster.html">集群（Cluster）</a></li>
<li><a href="cli.html">命令行参数</a></li>
<li><a href="console.html">控制台（Console）</a></li>
<li><a href="crypto.html">加密（Crypto）</a></li>
<li><a href="debugger.html">调试器</a></li>
<li><a href="deprecations.html">废弃的 API</a></li>
<li><a href="dns.html">DNS</a></li>
<li><a href="domain.html">域（Domain）</a></li>
<li><a href="esm.html">ECMAScript 模块</a></li>
<li><a href="errors.html">错误（Errors）</a></li>
<li><a href="events.html">事件（Events）</a></li>
<li><a href="fs.html">文件系统</a></li>
<li><a href="globals.html">全局对象（Globals）</a></li>
<li><a href="http.html">HTTP</a></li>
<li><a href="http2.html">HTTP/2</a></li>
<li><a href="https.html">HTTPS</a></li>
<li><a href="inspector.html">检查工具（Inspector）</a></li>
<li><a href="intl.html">国际化</a></li>
<li><a href="modules.html">模块（Modules）</a></li>
<li><a href="net.html">网络（Net）</a></li>
<li><a href="os.html">操作系统（OS）</a></li>
<li><a href="path.html">路径（Path）</a></li>
<li><a href="perf_hooks.html">性能钩子（Performance Hooks）</a></li>
<li><a href="process.html">进程</a></li>
<li><a href="punycode.html">Punycode</a></li>
<li><a href="querystring.html">查询字符串</a></li>
<li><a href="readline.html">逐行读取</a></li>
<li><a href="repl.html">交互式解释器（REPL）</a></li>
<li><a href="stream.html">流（Stream）</a></li>
<li><a href="string_decoder.html">字符串解码</a></li>
<li><a href="timers.html">定时器（Timers）</a></li>
<li><a href="tls.html">安全传输层（TLS/SSL）</a></li>
<li><a href="tracing.html">事件跟踪（Tracing）</a></li>
<li><a href="tty.html">TTY</a></li>
<li><a href="dgram.html">UDP / 数据报</a></li>
<li><a href="url.html">URL</a></li>
<li><a href="util.html">工具集</a></li>
<li><a href="v8.html">V8</a></li>
<li><a href="vm.html">虚拟机（VM）</a></li>
<li><a href="zlib.html">压缩（ZLIB）</a></li>
</ul>
<div class="line"></div>

<ul>
<li><a href="https://github.com/nodejs/node">GitHub 仓库和问题跟踪</a></li>
<li><a href="https://groups.google.com/group/nodejs">邮件列表</a></li>
</ul>
<!-- [end-include:_toc.md] -->

      
    </div>
  </div>
  <script src="assets/sh_main.js"></script>
  <script src="assets/sh_javascript.min.js"></script>
  <script>highlight(undefined, undefined, 'pre');</script>
</body>
</html>
